Back
Producer Integration Guide

Modified on 2016/03/01 17:15 by rrao Categorized as Uncategorized
==PRODUCER INTEGRATION GUIDE==

===Overview===

EZPrints Fulfillment Manager (FM) supports advanced order fulfillment network routing capabilities.  At a high level, we support receiving a single sales order, rendering images in a highly customizable way, and routing to multiple producers.  This guide details how to become a producer in the fulfillment network.  Producers are able to (1.) receive orders from FM and (2.) report order status information to FM.


===Receiving Orders from FM===

To receive orders from FM, two basic requirements must be met:

* <b>Expose an internet-facing HTTPS-based endpoint to receive HTTP POST requests containing orders in XML format.</b>
** The standard producer order XML format is documented below.  If a custom integration is required which deviates from our standard, please contact integration support.
** Web services or similar technologies may be utilized.
** We recommend and support passing standards-based internet authentication as a part of the HTTP requests. 
** As necessary, our public IP addresses are available upon request for white-listing purposes.

* <b>In the HTTP response of the order POST request, return specific information in XML format regarding the received order.</b>
** The standard response XML is documented below.  If a custom integration is required which deviates from our standard, please contact integration support.
** The standard response requires the word "Success" to be written somewhere in the response to the POST. 
** The standard response requires an attribute located in the XML named 'Reference', which contains a unique identifier corresponding to the producer's internal ID for the recieved order.  This field may be utilized for customer or technical support purposes.


===Reporting Order Status to FM===

To support sending order status to FM, we have a SOAP-based producer-focused web service located at the URI https://api.ezprints.com/producer.svc.  At this link, you may access the WSDL in various formats for importing into your development tools.  There are mandatory operations that producers must support, and optional operations which enhance customer support scenarios.  

* <b>Mandatory operations:</b>
** CompleteOrderShipment - indicates a single producer order was shipped and specifies shipment information.  Shipment information may include ship carrier, ship service, ship date/time in UTC format, and tracking information. Security credentials will be provided to you by your integration contact.
** RejectOrder - indicates a single producer order is unable to be produced for some reason.  

'''SAMPLE SOAP DOCUMENT - CompleteShipment'''{br}
Datetime stamps must be set to UTC

<pre><esc>    <s:Envelope>
      <s:Header>
        <a:Action s:mustUnderstand="1">http://www.ezprints.com/IProducerService/</a:Action>
        <a:MessageID>25E94F38-A191-4779-90C6-841DDA527680</a:MessageID>
        <a:ReplyTo>
          <a:Address>http://www.w3.org/2005/08/addressing/anonymous</a:Address>
        </a:ReplyTo>
        <a:To s:mustUnderstand="1">https://dev-api.ezprints.com/Producer.svc</a:To>
'''        <o:Security s:mustUnderstand ="1" xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
          <u:Timestamp u:Id="_0">
            <u:Created>2015-11-23T15:31:25Z</u:Created>
            <u:Expires>2015-11-23T15:36:25Z</u:Expires>
          </u:Timestamp>
          <o:UsernameToken u:Id="C4BBE33A-158E-4991-9A38-C55034F8445F"/>
            <o:Username><<USERNAME>></o:Username>
            <o:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText"><<PASSWORD>></o:Password>
          </o:UsernameToken>
        </o:Security>'''
      </s:Header>
    <s:Body>
      <CompleteOrderShipment xmlns="http://www.ezprints.com">
        <requestDto xmlns:b="http://schemas.datacontract.org/2004/07/EZP.Fulfillment.Communication.Data" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
          <b:ProducerOrderKey><<ProduceOrderKey>></b:ProducerOrderKey>
          <b:Shipments>
              <b:ShipmentInfoDto>
                <b:CarrierName>UPS</b:CarrierName>
                <b:ShipDateTime>2015-11-23T15:28:12Z</b:ShipDateTime>
                <b:ShipMethod>Ground</b:ShipMethod>
                <b:TrackingNumber>1Z283429490234834</b:TrackingNumber>
                  <b:Weight>2</b:Weight>
              </b:ShipmentInfoDto>
          </b:Shipments>
        </requestDto>
      </CompleteOrderShipment>
    </s:Body>
    </s:Envelope></esc></pre>

* <b>Optional operations:</b>
** SetOrderAssetsCollected - indicates a producer has completed collecting the images for a single producer order.
** SetOrderInProduction - indicates a producer has started fulfilling/producing a producer order.


===Sample Standard Producer Order Request XML===
Listed below is an example of an XML order you will receive in the body of the HTTP request.

<pre><esc>
<fo:ProducerOrder Reference="4059907" Key="P201509211436500351715XXX" xmlns:fo="http://messaging.ezprints.com/Schema/3.0/ProducerOrder">
  <fo:Extra>
    <Shipping Method="FC" />
  </fo:Extra>
  <fo:SalesOrder Key="S201509021425245621686XXX" OriginatorReference="AluminyzeTest001" CreateDateTime="9/2/2015 2:25:00 PM"CreateDateTimeFormatted="20150902022500" 
  OriginatorName="ez prints test " OriginatorNumber="405" LocationCode="" RetailCurrency="USD">
    <fo:Shipping>
      <fo:Address Address1="1890 Beaver Ridge cir" Address2="Suite B" City="Norcross" Company="" Country2="US" Country3="USA" PostalCode="30071"StateProvince="GA" />
      <fo:Contact Email="jdoe@test.com" Fax="555-555-1212" FirstName="John" LastName="Doe" Phone="555-555-1212" Title="" />
    </fo:Shipping>
    <fo:Vendor VendorUri="">
      <fo:Logo Id="64350728" Sort="logo" Type="Image" Uri="https://api.ezprints.com/GetAsset.ashx?Type=Producer&amp;ProducerOrderKey=P201509211436500351715536&amp;Key=logo&amp;Track=True" FileSize="631" Width="10" Height="10" />
    </fo:Vendor>
    <fo:Message>This is the a message that should show up on a packing slip</fo:Message>
  </fo:SalesOrder>
  <fo:Shipping>
    <fo:Address Address1="1890 Beaver Ridge cir" Address2="Suite B" City="Norcross" Company="" Country2="US" Country3="USA" PostalCode="30071"StateProvince="GA" />
    <fo:Contact Email="jdoe@test.com" Fax="555-555-1212" FirstName="John" LastName="Doe" Phone="555-555-1212" Title="" />
  </fo:Shipping>
  <fo:OrderLine Key="1" Reference="59631536" Sku="S12X12" Quantity="1" Name="12x12 Aluminum 3/4&quot; Wall Float - Glossy - White"Description="12x12 Aluminum 3/4&quot; Wall Float - Glossy - White" ProjectId="14t8-dvcl-rn6v-z0rz" OriginatorDescription="12x12 Aluminum 3/4&quot;Wall Float - Glossy - White">
    <fo:Product Type="Originator" Sku="87516" Name="" Description="" />
    <fo:Product Type="Sales" Sku="87516" Name="12x12 Aluminum 3/4&quot; Wall Float - Glossy - White" Description="12x12 Aluminum 3/4&quot; Wall Float - Glossy - White" />
    <fo:Product Type="Base" Sku="87516" Name="12x12 Aluminum 3/4&quot; Wall Float - Glossy - White" Description="12x12 Aluminum 3/4&quot; Wall Float - Glossy - White" />
    <fo:Product Type="Producer" Sku="S12X12" />
    <fo:Asset Id="64350781" Sort="1" Type="Image" Uri="https://api.ezprints.com/GetAsset.ashx?Type=Producer&amp;ProducerOrderKey=P201509211436500351715536&amp;ProducerOrderLineKey=1&amp;Key=1&amp;Track=True" FileSize="3380655" Width="1815"Height="1815" />
  </fo:OrderLine>
</fo:ProducerOrder>
</esc></pre>

===Sample Standard Producer Order Response XML===
Listed below are the recommended HTTP responses as a result of the order HTTP request.  

Example successful response:
<pre><esc>
<OrderResponse Success="true" Reference="YourInternalOrderId" Message="" />
</esc></pre>

Example failed response:
<pre><esc>
<OrderResponse Success="false" Reference="" Message="Some error message pertaining to the order request" />
</esc></pre>


===Producer Order XML Elements and Content===

Listed below is a description of selected producer order XML elements and associated content.

{| cellspacing="0" cellpadding="2"
! Element Name !! Child Name !! Element or Attribute? !! Required !! Element Cardinality !! Description<span style="display: block;width: 200px;"></span>
|-
| ProducerOrder
| <!-- empty -->
| Element
| Required 
| Only 1
| Root element of producer order.
|-
| ProducerOrder
| Key
| Attribute
| Required 
| Only 1
| Primary unique identifier for a producer order.  We recommend you store this value in your internal systems for customer and technical support purposes.
|-
| ProducerOrder
| Reference
| Attribute
| Optional 
| Only 1
| Secondary identifier for a producer order.  Not guaranteed to be unique.
|-
| ProducerOrder
| Extra
| Element
| Required for physical delivery orders.   
| Only 1
| Extra metadata associated with an order.  
|-
| ProducerOrder
| Vendor
| Element
| Required for white label branding
| Only 1
| Contains Originator Logo information
|-
| Logo
| Uri
| Attribute
| Required for white label branding
| Only 1
| Originator Logo Uri
|-
| Extra
| Shipping
| Element
| Required for physical delivery orders.  Will be deprecated in future release. 
| Only 1
| Contains information related to shipment commitment. 
|-
| Extra/Shipping
| Method
| Attribute
| Indicates shipping commitment level. 
| Only 1
| Code of shipping method. Valid shipping codes are 'FC', 'PM', 'SD', and 'ON'.  FC = first class, PM = priority mail, SD = second day, ON = overnight.
|-
| ProducerOrder
| SalesOrder
| Element
| Required
| Only 1
| Contains information from the original sales order placed by the business partner's customer.  All information should be ignored/not utilized by producer.
|-
| ProducerOrder
| Shipping
| Element
| Required
| Only 1
| Contains the order ship-to information.
|-
| ProducerOrder/Shipping
| Address
| Element
| Required
| Only 1
| Contains the order ship-to address.
|-
| ProducerOrder/Shipping
| Contact
| Element
| Required
| Only 1
| Contains the order ship-to customer details.
|-
| ProducerOrder
| OrderLine
| Element
| Required
| 1 or more
| Contains information about an order line item and associated digital assets.
|-
| OrderLine
| Reference
| Attribute
| Required
| Only 1
| FM internal reference for a producer order line.  Uniquely identifies a producer order line within a single producer order.
|-
| OrderLine
| Sku
| Attribute
| Required
| Only 1
| Alphanumeric code associated with product being ordered.
|-
| OrderLine
| Quantity
| Attribute
| Required
| Only 1
| Units to produce
|-
| OrderLine
| Description
| Attribute
| Required
| Only 1
| Description of product sku being ordered.
|-
| OrderLine
| Asset
| Element
| Required
| 1 or more
| Digital asset/file associated with order line.  Number of Asset's depends on the product sku being ordered.
|-
| Asset
| Id
| Attribute
| Required
| Only 1
| FM internal ID for a producer order line asset.  
|-
| Asset
| Sort
| Attribute
| Required
| Only 1
| Specifies ordering of assets for an order item.  I.e., some product skus may require a specific ordering of images (e.g., photo books).
|-
| Asset
| Type
| Attribute
| Required
| Only 1
| Indicates the general image category.  Valid values are 'Raw', 'PDF', and 'Image'.  We recommend using the content-type on the download asset HTTP request for determining exact file type.
|-
| Asset
| Uri
| Attribute
| Required
| Only 1
| URI to the high-resolution image.
|}
Meta Keywords:
Meta Description:
Change Comment: